pp108 : Configuring SAML 2.0 Authenticator

Configuring SAML 2.0 Authenticator
This topic describes the procedure to configure a SAML 2.0 Authenticator used for user interface based authentication.

Before you begin this task:
You must get the metadata from the external Identity Provider (IdP) and save it at a known location. You will need it during the configuration process.


Sometimes, there can be a requirement to use an external SAML 2.0 IdP for authenticating users in Process Platform. With the SAML 2.0 functionality, it becomes easy to configure the integration between the external Identity Provider (IdP) and Process Platform which acts as a Service Provider (SP). The IdP can be configured according to the security needs of the application, and Process Platform can be configured to trust this SAML 2.0 compliant IdP. If there is no specific security requirement for user authentication, then the Process Platform built-in authentication mechanism can be used.

SAML 2.0 Metadata
The configuration of a Trust relation between an external Identity Provider and Process Platform as SP can be done as follows:

  1. Configure or import the SAML 2.0 IdP metadata in Process Platform as described below and import the SAML 2.0 SP metadata in the IdP. The SAML 2.0 IdP metadata is added to a SAML Authenticator configuration.
  2. To export the Process Platform SP SAML 2.0 metadata for the IdP also, use the Security Administration. Select the Authenticator for which you want to export the SP metadata and click Get Metadata and add it to the external IdP. In some IdPs the SAML 2.0 SP metadata needs to be imported through a URL. This can be done by using the metadata URL which will export the SAML 2.0 SP metadata through this URL.


To setup Process Platform as SP and work together with an external IdP, the administrator has to create an Authenticator. An Authenticator defines which IdP will be used for authenticating the users.

  1. On CUSP > My Applications App Palette, open Security Administration, select Authenticators, and do one of the following:
    • Click on the Shared Authenticators grid to create an authenticator for all the organizations.
    • Click on the Organizational Authenticators grid to create an authenticator for all the users in a specific organization. The Authenticator Properties dialog box appears.
  2. Provide a unique identifier, for the Authenticator, in the ID field. This must be unique for each authenticator.
  3. Select SAML2.0 Authenticator from the Type drop-down list.
  4. Select the Default check box if you want to mark this authenticator as the default authenticator.
  5. Select the Test only check box if you only want to Test this Authenticator before making it Default. The Test Url field will display the URL that is used to access the Process Platform instance with this Authenticator configuration active.
  6. Provide a description in the Description field.
  7. Provide a URL in the Change Password URL field. Users will be directed to this URL when they want to modify the password.
  8. In the FrameProperties section, do the following:
    • Select No Frame check box, if you do not want any frame around the Login form.

      Note: This option will do a complete page reload resulting in losing the browser context. With this option users can view the complete URL of the external Identity Provider, which gives more trust to the users as they can validate going to a trusted site before providing username and password. This is the default and most secure setting.

    • Select Maximize check box if you want the Login form to be displayed in a maximized frame.
    • If required, modify the Width and Height of the Frame that will display the Login form.
    • You can use the Target Frame field, to prevent the display of the complete form, in case Process Platform Forms are displayed in a portal, like Process Experience. In that case, specify the value CordysRoot as Target Frame. Generally, after the users are authenticated, the complete Form is reloaded. If you specify CordysRoot as Target Frame, the complete form is not displayed and instead only the part of the portal where the Process Platform Form is displayed is reloaded.
  9. Paste the metadata, that you retrieved from the external IdP, in the Entity Descriptor field of SAML2.0 Properties tab.

    Note: The SAML 2.0 IdP metadata is very important to establish trust between the IdP and the Process Platform instance. The metadata contains information such as Login URL, Logout URL, and certificates used for signing the SAML2 assertion.

  10. Click Save.

Depending upon your choice, the SAML 2.0 Authenticator is configured and added to either the Shared Authenticators list or Organizational Authenticators list.

Using the CordysBuiltIn Authenticator

If accessing the default SAML Authenticator results in an unrecoverable error, the Administrator still can login and correct the wrong configuration using the Process Platform Built-in Authenticator.
To access the Process Platform Built-in Authenticator, you must use the authID URL parameter with the value CordysBuiltIn. This bypasses any default configured Authenticator and displays the built-in Process Platform Login page.
Example:

https://www.acme.com/home/myorg/?authID=CordysBuiltIn

Note: In case, for security reasons, the admins do not want to allow access to the Process Platform Built-in Authenticator, they can block access to the SAML Authentication Request Web service through ACL.

Configuration Examples

For a detailed example on integrating Process Platform with external IdP, see Security Management in the Process Platform Community.

After you complete this task:

The signing certificate of the external IdP will have a certificate chain. You need to add the certificates in that certificate chain to the Trust Store. Before you add the certificates, select the SAML 2.0 IDP Issuer Certificate check box under Trust Context List.